<!-- HTML header for doxygen 1.8.13-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.13"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>MTB CAT1 Peripheral driver library: Cryptolite   (Cryptography)</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen_style.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><a href="http://www.cypress.com/"><img alt="Logo" src="IFXCYP_one-line.png"/></a></td>
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">MTB CAT1 Peripheral driver library</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('group__group__cryptolite.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="summary">
<a href="#groups">API Reference</a>  </div>
  <div class="headertitle">
<div class="title">Cryptolite (Cryptography)</div>  </div>
</div><!--header-->
<div class="contents">
<a name="details" id="details"></a><h2 class="groupheader">General Description</h2>
<dl class="section note"><dt>Note</dt><dd>IP Supported: CRYPTOLITE </dd>
<dd>
Availability of Cryptolite Algorithms will be chip specific, Refer to individual API for availability. </dd>
<dd>
Device Categories: CAT1B. Please refer <a href="usergroup1.html">Device Catalog</a>.</dd></dl>
<p>The PDL Cryptolite driver provides a public API to perform hardware accelerated cryptographic calculations.</p>
<p>The functions and other declarations used in this driver are in cy_cryptolite.h. You can also include cy_pdl.h to get access to all functions and declarations in the PDL.</p>
<p>The Cryptolite driver supports AES (128bits), SHA-256, HMAC-SHA256, TRNG, RSA, ECDSA, EDDSA.</p>
<dl class="section note"><dt>Note</dt><dd>For EDDSA, user application needs to implement SHA-512 functions. The prototypes of SHA functions are available in <a class="el" href="structcy__stc__cryptolite__ed25519__sha512__t.html">cy_stc_cryptolite_ed25519_sha512_t</a>. There is also separate EDDSA <a class="el" href="group__group__cryptolite__lld__asymmetric__functions.html#ga03448216ebbb2734e3e4e8f7f529bef5">Cy_Cryptolite_ED25519_Init</a> and <a class="el" href="group__group__cryptolite__lld__asymmetric__functions.html#ga67493f2f433700b504e285bb9c441e14">Cy_Cryptolite_ED25519_Free</a> functions needs to be called.</dd></dl>
<h1><a class="anchor" id="group_cryptolite_configuration_considerations"></a>
Configuration Considerations</h1>
<p>User can enable/disable cryptographic functionality based on the project requirements. To do so, create a configuration header file to configure cryptographic functionalities and define a macro CY_CRYPTOLITE_USER_CONFIG_FILE with configuration header file name and add to project environment. If CY_CRYPTOLITE_USER_CONFIG_FILE macro is not defined in project environment, firmware will enable all available cryptographic functionalities.</p>
<p>Firmware sets up a cryptographic operation by passing in the required data as parameters in the function calls.</p>
<p>All Cryptolite function require a context. A context is a data structure that the driver uses for its operations. Firmware declares a context (allocates memory) but does not write or read the values in that context. In effect, the context is a scratch pad you provide to the driver. The driver uses the context to store and manipulate data during cryptographic operations. The Cryptolite driver header file declare all the required structures for context.</p>
<h1><a class="anchor" id="group_cryptolite_sha256_definitions"></a>
Definitions</h1>
<table class="doxtable">
<tr>
<th>Term </th><th><p class="starttd">Definition </p>
<p class="endtd"></p>
</th></tr>
<tr>
<td>Secure Hash Algorithm (SHA) </td><td>A cryptographic hash function. This function takes a message of an arbitrary length and reduces it to a fixed-length residue or message digest after performing a series of mathematically defined operations that practically guarantee that any change in the message will change the hash value. It is used for message authentication by transmitting a message with a hash value appended to it and recalculating the message hash value using the same algorithm at the recipient's end. If the hashes differ, then the message is corrupted. For more information see <a href="https://csrc.nist.gov/csrc/media/publications/fips/180/2/archive/2002-08-01/documents/fips180-2.pdf">Secure Hash standard description</a>.   </td></tr>
<tr>
<td>Plaintext </td><td><p class="starttd">An unencrypted message </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>Ciphertext </td><td><p class="starttd">An encrypted message </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>Block Cipher </td><td><p class="starttd">An encryption function for fixed-size blocks of data. This function takes a fixed-size key and a block of plaintext data from the message and encrypts it to generate ciphertext. Block ciphers are reversible. The function performed on a block of encrypted data will decrypt that data. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>Block Cipher Mode </td><td>A mode of encrypting a message using block ciphers for messages of an arbitrary length. The message is padded so that its length is an integer multiple of the block size. ECB (Electronic Code Book), CBC (Cipher Block Chaining), and CFB (Cipher Feedback) are all modes of using block ciphers to create an encrypted message of an arbitrary length.   </td></tr>
<tr>
<td>Advanced Encryption Standard (AES) </td><td>The <a href="https://nvlpubs.nist.gov/nistpubs/fips/nist.fips.197.pdf">AES standard</a> specifies the Rijndael algorithm, a symmetric block cipher that can process 128-bit data blocks, using cipher keys with 128-, 192-, and 256-bit lengths. Rijndael was designed to handle additional block sizes and key lengths. However, they are not adopted in this standard. AES is also used for message authentication.   </td></tr>
<tr>
<td>Message Authentication Code (MAC) </td><td><p class="starttd">MACs are used to verify that a received message has not been altered. This is done by first computing a MAC value at the sender's end and appending it to the transmitted message. When the message is received, the MAC is computed again and checked against the MAC value transmitted with the message. If they do not match, the message has been altered. Either a Hash algorithm (such as SHA) or a block cipher (such as AES) can be used to produce the MAC value. Keyed MAC schemes use a Secret Key along with the message, thus the Key value must be known to be able to compute the MAC value. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>Hash Message Authentication Code (HMAC) </td><td>A specific type of message authentication code (MAC) that involves a cryptographic hash function and a secret cryptographic key. It computes the MAC value using a Hash algorithm. For more information see <a href="https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.198-1.pdf">The Keyed-Hash Message Authentication Code standard</a>   </td></tr>
<tr>
<td>True Random Number Generator (TRNG) </td><td><p class="starttd">A block that generates a number that is statistically random and based on some physical random variation. The number cannot be duplicated by running the process again. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>Symmetric Key Cryptography </td><td><p class="starttd">Uses a common, known key to encrypt and decrypt messages (a shared secret between sender and receiver). An efficient method used for encrypting and decrypting messages after the authenticity of the other party has been established. AES is well-known symmetric cryptography methods. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>Asymmetric Key Cryptography </td><td><p class="starttd">Also referred to as Public Key encryption. To receive a message, you publish a very large public key (up to 4096 bits currently). The public key is described by the pair (n, e) where n is a product of two randomly chosen primes p and q. The exponent e is a random integer 1 &lt; e &lt; Q where Q = (p-1) (q-1). The private key d is uniquely defined by the integer 1 &lt; d &lt; Q so that ed congruent with 1 (mod Q ). To send a message to the publisher of the public key, you encrypt the message with the public key. This message can now be decrypted only with the private key. The message is now sent over any channel to the recipient who can decrypt it with the private (secret) key. The same process is used to send messages to the sender of the original message. The asymmetric cryptography relies on the mathematical impracticality (usually related to the processing power available at any given time) of factoring the keys.  </p>
<p class="endtd"></p>
</td></tr>
</table>
<h1><a class="anchor" id="group_cryptolite_changelog"></a>
Changelog</h1>
<table class="doxtable">
<tr>
<th>Version</th><th>Changes</th><th>Reason for Change </th></tr>
<tr>
<td>2.80 </td><td><ul>
<li>
Added new API's <a class="el" href="group__group__cryptolite__lld__asymmetric__functions.html#ga03448216ebbb2734e3e4e8f7f529bef5">Cy_Cryptolite_ED25519_Init</a>, <a class="el" href="group__group__cryptolite__lld__asymmetric__functions.html#ga67493f2f433700b504e285bb9c441e14">Cy_Cryptolite_ED25519_Free</a>, <a class="el" href="group__group__cryptolite__lld__asymmetric__functions.html#ga29c1a7ef06306d435299906f9cf40cbc">Cy_Cryptolite_ED25519_Sign</a>, <a class="el" href="group__group__cryptolite__lld__asymmetric__functions.html#ga3735e882a1dd88dec12cbd5be9514921">Cy_Cryptolite_ED25519_PointMultiplication</a>, <a class="el" href="group__group__cryptolite__lld__asymmetric__functions.html#ga87ebcde6d856c570808beb799987e174">Cy_Cryptolite_ED25519_PointDecode</a>, <a class="el" href="group__group__cryptolite__lld__asymmetric__functions.html#ga5528eb2740efe02150020148a4a06d09">Cy_Cryptolite_ED25519_Verify</a>, <a class="el" href="group__group__cryptolite__lld__asymmetric__functions.html#gad23cb5ab0498b2541505588d2cf8dc9d">Cy_Cryptolite_ED25519_MakePublicKey</a>, <a class="el" href="group__group__cryptolite__lld__asymmetric__functions.html#gad1f2fa8d05fc6f027e2a5e97f5f8da7b">Cy_Cryptolite_EC25519_MakePublicKey</a>, <a class="el" href="group__group__cryptolite__lld__asymmetric__functions.html#ga60c4e3a7ccbdd45250001ee8e3078545">Cy_Cryptolite_EC25519_PointMultiplication</a>. </li>
<li>
Added new function pointers <a class="el" href="group__group__crypto__lld__asymmetric__functions.html#gafb50caadc8ad53e03011d523e49cf022">cy_func_get_random_data_t</a>, <a class="el" href="group__group__cryptolite__lld__asymmetric__functions.html#gafdf03c51442ff5e88b6b19bb4b7ec28c">cy_cryptolite_ed25519_sha512_init_t</a>, <a class="el" href="group__group__cryptolite__lld__asymmetric__functions.html#gaa4679df6ed15d5d6f1f465124bee09cc">cy_cryptolite_ed25519_sha512_update_t</a>, <a class="el" href="group__group__cryptolite__lld__asymmetric__functions.html#ga0d14f9b46c20ef7d69679fef91aefeef">cy_cryptolite_ed25519_sha512_start_t</a>, <a class="el" href="group__group__cryptolite__lld__asymmetric__functions.html#ga5fde282bff76e1649bcaafd992c0a549">cy_cryptolite_ed25519_sha512_finish_t</a>, <a class="el" href="group__group__cryptolite__lld__asymmetric__functions.html#gaf14f955ab143879a414a7a31aff76aa7">cy_cryptolite_ed25519_sha512_free_t</a>. </li>
<li>
Added new enum <a class="el" href="group__group__cryptolite__enums.html#gafa2003583345983638b3326bd52f22cd">cy_en_cryptolite_eddsa_sig_type_t</a>. Added new structures <a class="el" href="structcy__stc__cryptolite__ec25519__dp__type.html">cy_stc_cryptolite_ec25519_dp_type</a>, <a class="el" href="structcy__stc__cryptolite__ed25519__sha512__t.html">cy_stc_cryptolite_ed25519_sha512_t</a>. </li>
<li>
Added new macros  </li>
<li>
updated API's <a class="el" href="group__group__cryptolite__lld__mac__functions.html#ga10110e926b2aaab977e04e79e03ee64d">Cy_Cryptolite_Cmac_Update</a>, <a class="el" href="group__group__cryptolite__lld__aes__functions.html#ga667d244bfb6bb87154abd125006da6f6">Cy_Cryptolite_Aes_Ecb_Update</a>, <a class="el" href="group__group__cryptolite__lld__aes__functions.html#ga94393977551a3fa576c70119449d8903">Cy_Cryptolite_Aes_Cbc_Update</a>. </li>
<li>
<p class="startli">updated enum <a class="el" href="group__group__cryptolite__enums.html#ga3b051ef176b1e1a9811acbae28eb2360">cy_en_cryptolite_ecc_curve_id_t</a>. updated structure <a class="el" href="structcy__stc__cryptolite__context__ecdsa__t.html">cy_stc_cryptolite_context_ecdsa_t</a>.</p>
<p class="endli"></p>
</li>
</ul>
</td><td>Added support for amazon sidewalk crypto requirement.  </td></tr>
<tr>
<td>2.70 </td><td>Updated structure <a class="el" href="structcy__stc__cryptolite__context__sha256__t.html">cy_stc_cryptolite_context_sha256_t</a>.  </td><td>Bug fixes  </td></tr>
<tr>
<td>2.60 </td><td><ul>
<li>
Added new API <a class="el" href="group__group__cryptolite__lld__asymmetric__functions.html#ga9ce421065ec73beb963ed06298726e91">Cy_Cryptolite_ECC_SharedSecret</a>. </li>
<li>
Updated APIs <a class="el" href="group__group__cryptolite__lld__sha__functions.html#ga579de23a52612ca00d5c0e499f6e9b9a">Cy_Cryptolite_Sha256_Start</a>, <a class="el" href="group__group__cryptolite__lld__sha__functions.html#ga27bd7bb768df3fd2158fe87823d418ad">Cy_Cryptolite_Sha256_Update</a>, <a class="el" href="group__group__cryptolite__lld__aes__functions.html#ga013214e8bfeb2e987bf1f7e5356a95d0">Cy_Cryptolite_Aes_Ccm_Finish</a> </li>
</ul>
</td><td>Added ECDH support for CAT1B devices and Bug fixes  </td></tr>
<tr>
<td>2.50 </td><td><ul>
<li>
Support for AES-CCM, AES-CMAC, AES-CBC-MAC &amp; AES multistage for modes ECB, CBC, CFB, CTR added. </li>
<li>
Support for HKDF added. </li>
<li>
Support for ECC key pair generation &amp; ECDSA Sign added . </li>
</ul>
</td><td></td></tr>
<tr>
<td>2.40 </td><td>Updated value of CY_CRYPTOLITE_DEF_TRNG_GARO macro. </td><td>Usability enhancement.  </td></tr>
<tr>
<td>2.30 </td><td>Updated APIs <a class="el" href="group__group__cryptolite__lld__asymmetric__functions.html#ga956dd70a876047166b391430eb7d1c58">Cy_Cryptolite_ECC_VerifyHash</a> and <a class="el" href="group__group__cryptolite__lld__aes__functions.html#ga96a14d14eef1ba7bf51a97ff809cce84">Cy_Cryptolite_Aes_Ctr</a>. </td><td>Support for ECDSA verify for HASHZERO message added and MISRA 2012 violation fix  </td></tr>
<tr>
<td>2.20 </td><td><ul>
<li>
Updated TRNG default config. </li>
</ul>
</td><td></td></tr>
<tr>
<td>2.10 </td><td><ul>
<li>
Added HMAC-SHA256 &amp; AES(128 bit) support. </li>
<li>
Added TRNG support. </li>
<li>
Added RSA signature verification support upto 4096 bit </li>
<li>
Added ECDSA signature verification support for SECP256R1 &amp; SECP384R1 </li>
</ul>
</td><td></td></tr>
<tr>
<td>2.0 </td><td>Renamed the sha256 context structure from cy_stc_cryptolite_context_sha_t to <a class="el" href="structcy__stc__cryptolite__context__sha256__t.html" title="The structure for storing the SHA256 context. ">cy_stc_cryptolite_context_sha256_t</a>  </td><td></td></tr>
<tr>
<td>1.0 </td><td>Initial Version </td><td></td></tr>
</table>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="groups"></a>
API Reference</h2></td></tr>
<tr class="memitem:group__group__cryptolite__lld__sha"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__group__cryptolite__lld__sha.html">Hash operations (SHA)</a></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:group__group__cryptolite__lld__mac"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__group__cryptolite__lld__mac.html">Message Authentication Code (HMAC, CMAC)</a></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:group__group__cryptolite__lld__aes"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__group__cryptolite__lld__aes.html">Symmetric Key Algorithm (AES)</a></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:group__group__cryptolite__lld__kdf"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__group__cryptolite__lld__kdf.html">Key Derivative Function (HKDF)</a></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:group__group__cryptolite__lld__asymmetric"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__group__cryptolite__lld__asymmetric.html">Asymmetric Key Algorithm (RSA,ECP,ECDSA,EDDSA)</a></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:group__group__cryptolite__lld__keygen"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__group__cryptolite__lld__keygen.html">Key Generation (ECP)</a></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:group__group__cryptolite__lld__random__number"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__group__cryptolite__lld__random__number.html">Random Number Generation(TRNG)</a></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:group__group__cryptolite__lld__vu"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__group__cryptolite__lld__vu.html">Vector Unit (VU)</a></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:group__group__cryptolite__data__structures"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__group__cryptolite__data__structures.html">Common Data Structures</a></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:group__group__cryptolite__enums"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__group__cryptolite__enums.html">Common Enumerated Types</a></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:group__group__cryptolite__macros"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__group__cryptolite__macros.html">Macros</a></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
</div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part
<div id="nav-path" class="navpath">
    <ul>
        <li class="footer">
            Generated for <b>MTB CAT1 Peripheral driver library</b> by <b>Cypress Semiconductor Corporation</b>.
            All rights reserved.
        </li>
    </ul>
</div>
-->
</body>
</html>
